Asset Management
Namespace: $GG.ui.assets
Related Topics
The $GG.ui.assets namespace is responsible for managing various types of assets within the application, such as images, videos, and audio files. It provides functions to dynamically load, preload, and retrieve these assets, ensuring they are readily available for use when needed. This namespace is essential for efficient asset management, allowing for asynchronous loading and caching of resources.
Include In Html
<head>
...
<script src="https://launch.gig.game/api/js?key={API KEY HERE}&libraries=ui"></script>
...
</head>
JSON Asset File
Assets can be preloaded from an asset sheet to streamline management and enhance performance. Preloading assets ensures that they are readily available when needed, reducing load times and preventing delays during runtime. The asset sheet is a JSON file that lists all assets, including their types and file paths, in a structured and organized manner. It also supports defining sprite animations with clipping paths and complex layouts made up of multiple images. Below is an example of the basic format of a JSON asset sheet file, demonstrating how different assets are categorized and referenced for efficient preloading and access.
Example JSON Asset Sheet:
//all of these assets get automatically preloaded
{
"audio": [
{
//audio type
"name": "steps",
"path": "assets/audio/footsteps.mp3"
},
{
"name": "pop",
"path": "assets/audio/pop.mp3"
},
{
"name": "song",
"path": "assets/audio/song.mp3"
},
{
"name": "applause",
"path": "assets/audio/applause.mp3"
}
],
"videos": [
{
//video type
"name": "samplevideo",
"path": "assets/video/sample.mp4"
}
],
"images": [
{
//image type
"name": "grass",
"path": "assets/images/grass.png"
},
{
"name": "grassbottom",
"path": "assets/images/bottom.png"
},
{
//sprite type of two images which can alternate on a given frame rate. This can be as many as you wish.
"group": "bird",
"path": "assets/images/sprite-sheet.png",
"clipPaths": [
{
//image type is cut out of sprite sheet using clip path
"name": "fly-1",
"clipPath": [
{
"x": 10.0,
"y": 10.0
},
{
"x": 10.0,
"y": 50.0
},
{
"x": 50.0,
"y": 50.0
},
{
"x": 50.0,
"y": 10.0
}
]
},
{
//image type is cut out of sprite sheet using clip path
"name": "fly-2",
"clipPath": [
{
"x": 60.0,
"y": 10.0
},
{
"x": 60.0,
"y": 50.0
},
{
"x": 100.0,
"y": 50.0
},
{
"x": 100.0,
"y": 10.0
}
]
}
]
}
],
"layouts": [
{
"name": "basic yard",
"tiles": [
{
"x": 0,
"y": 0,
"frameRate": 12,
"frameStart": 0,
"imageName": "grass" //references image name
},
{
"x": 200,
"y": 0,
"frameRate": 12,
"frameStart": 0,
"imageName": "grass"
},
{
"x": 0,
"y": 200,
"frameRate": 12,
"frameStart": 0,
"imageName": "grassbottom"
},
{
"x": 200,
"y": 200,
"frameRate": 12,
"frameStart": 0,
"imageName": "grassbottom"
}
]
}
]
"data": [
{
"name": "mydata",
"object": {} //any object or array you want. you decide the schema on these.
}
]
}
Loading Example
To load the assets from the JSON asset sheet and use them in your application, you can use the following JavaScript code:
$GG.ui.assets
.loadAssetFile("assets/assets.json")
.then(() => {
// this would play applause from the above assets sheet
$GG.ui.audio.play("applause", false, 0.5);
})
.catch((error) => {
// Log an error message if the asset loading fails
console.error(`Error loading asset sheet`, error);
});
Types
These asset types are primarily defined in the asset file format, with additional properties added during processing by the asset manager.
Weak Types Returned by Methods:
- Image: {name?: string, path: string, clipPath? : Array< {x: number,y: number} >, Image: Image, ActiveStage: Canvas, CanvasContext: Context }
- Video: {name?: string, path: string, Video: Video }
- Audio: {name?: string, path: string, Audio: Audio }
- Sprite: {name?: string, path: string, clipPaths: Array< Image > }
- Layout: {name?: string, tiles: Array<{x: number, y:number , frameRate: number, frameStart: number, imageName: string}> }
- Data: {name: string, object: object }
Format and Naming
To ensure that assets can be efficiently accessed and managed, each asset should ideally have a unique name. This naming allows you to reference assets directly by their names in your code. If an asset is provided without a name, it will be cached for performance reasons but cannot be accessed by name. Instead, it will be stored in memory, and you would need to access it through other means, such as by its file path.
Images
Images in the asset management system can be handled in different ways to suit various needs:
Standalone Images: These are individual image files that can be used directly in your application. They are loaded and cached for efficient retrieval.
Sprite Sheets: Images can also be combined into a single PNG sprite sheet. A sprite sheet is a large image that contains multiple smaller images arranged in a grid or other layout. This method is useful for animations and organizing related images.
- Clipping Paths: When using sprite sheets, you can define clipping paths to specify the exact area of the sprite sheet that corresponds to each individual image. A clipping path is essentially a rectangle (or polygon) that cuts out a section of the sprite sheet to be used as a distinct image by name. This is especially useful for sprites where multiple frames of animation are stored in one file.
Sprites: Sprites are a special type of image used for animation. They involve a group of images (frames) that are displayed in sequence to create the illusion of movement. Each sprite is associated with a frame rate, which determines how quickly the frames change to produce smooth animations. Sprites are defined with a
groupname and have a set ofclipPathsto define the frames of animation within a sprite sheet. For example, a character sprite might have multiple frames showing different walking poses.
Layouts
Layouts are a way to create complex scenes or backgrounds by composing smaller images and sprites. They allow you to define a larger image by placing and arranging tiles or sprites in a specific pattern.
Tiles: Each tile in a layout is an individual image or sprite positioned at a specific coordinate. You can specify properties such as frame rate and starting frame for animated tiles.
Properties: The layout specifies the
xandycoordinates for each tile, as well as any additional properties needed for rendering or animation. This allows you to build up a detailed scene by arranging tiles in a grid or other pattern.
Videos and Audio
Videos: Video files are preloaded and cached similarly to images and audio. However, caching behavior can vary depending on the operating system and browser. For example, some systems, like macOS, may not effectively cache videos, leading to potential delays on first play.
Audio: Audio files are also preloaded and cached to minimize delays during playback. As with videos, caching behavior can be affected by operating system limitations.
Data
In addition to multimedia assets, you can store custom, named data in your asset sheet. This data can be in any format, such as objects or arrays, and is useful for storing configuration settings, game state, or other relevant information.
- Schema: The schema for custom data is flexible, allowing you to define it according to your application's needs. You can include various types of data, such as game configuration, player stats, or other dynamic content that your application might need.
By carefully structuring and naming your assets, you ensure that they are easy to manage, access, and use within your application, leading to a more organized and efficient development process.